home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 April: Mac OS SDK / Dev.CD Apr 96 SDK / Dev.CD Apr 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / Documentation / Tech Notes & Articles / Recipes / Part Persistency / Display Frame 'ternalization < prev    next >
Encoding:
Text File  |  1995-04-21  |  5.7 KB  |  232 lines  |  [TEXT/ttxt]

  1. OpenDoc™ Recipes
  2.  
  3.  
  4. Display Frame 'ternalization
  5. By The OpenDoc Design Team
  6. April 20th, 1995
  7.  
  8.  
  9. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  10. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  11. Mac and OpenDoc are trademarks of Apple Computer, Inc. 
  12.  
  13.  
  14.  
  15.  
  16. Introduction
  17.  
  18. A well behaved part editor needs keep track of it's display frames, and store & retrieve them from an annotation property on its storageunit.   This document contains the list of methods affected, and a brief description of their responsibilities.  The sample code documents step by step how to implement this functionality in those methods.  
  19.  
  20.  
  21. Caveats
  22.  
  23. • This code contains minimal proper error checking
  24. • It does not account for the case where a part may want to do AbstractTertiaryCase.
  25. • It uses the CLink and CLinkedList classes which are an unsupported utility of OpenDoc.
  26. • It uses StorUtil.h and StdTypIO.h which are two more unsupported utilities of OpenDoc.  It is recommended that you copy the sample code from these unsupported utilities into your project.
  27. • It does not contain any optimizations such as lazily internalizing your display frames, or only rewriting your list of display frames when it changes.
  28. • Sample Code taken from "SamplePart".
  29. • Sample Code may not contain all the necessary #includes.
  30. • Sample Code is written with the assumption that the rest of the implementation follows the SOM Wrapper/C++ Implementation strategy.
  31. • Sample Code does not contain full implementation for the methods listed.  Sample Code is intended to be added to the implementation of the methods listed.
  32.  
  33. Methods Affected
  34.  
  35. • Constructor
  36. Clear fDisplayFrames.
  37.  
  38. • Destructor
  39. Delete fDisplayFrames if it is not null, and set it to null.
  40.  
  41. • InitPart
  42. Create a new, empty collection (fDisplayFrames) in which to store a list of your display frames.
  43.  
  44. • DisplayFrameAdded
  45. Add the frame passed in to fDisplayFrames.
  46.  
  47. • DisplayFrameConnected
  48. Add the frame passed in to fDisplayFrames if it is not already in the list.
  49.  
  50. • DisplayFrameRemoved 
  51. Remove the frame passed in from fDisplayFrames.
  52.  
  53. • DisplayFrameClosed 
  54. Remove the frame passed in from fDisplayFrames.
  55.  
  56. • Externalize
  57. If necessary create a DisplayFrames annotation property and StorageUnitRefs value on your storageunit.
  58. Otherwise just focus to your DisplayFrames annotation property and its StorageUnitRefs value.
  59. Write out a list of references to your display frames from fDisplayFrames.
  60.  
  61. • InitPartFromStorage
  62. Focus to your DisplayFrames annotation property and its StorageUnitRefs value.
  63. Read in the list of your display frames into fDisplayFrames.  See the Lazy Frame Internalization recipe for more info.
  64.  
  65. • ReleaseAll
  66. Assert that you fDisplayFrames collection is empty.
  67.  
  68. Sample Code
  69.  
  70. void CMyPart::CMyPart()
  71. {
  72.     fDisplayFrames = kODNULL;
  73. }
  74.  
  75. void CMyPart::~CMyPart()
  76. {
  77.     if (fDisplayFrames != kODNULL)
  78.  {
  79.   delete fDisplayFrames;
  80.   fDisplayFrames = kODNULL;
  81.  }
  82. }
  83.  
  84.  
  85. void CMyPart::InitPart(
  86.                 Environment*                ev,
  87.                 ODStorageUnit*                storageUnit,
  88.                 ODPart*                        partWrapper
  89. )
  90. {
  91.     // Create a list to keep track of the frames we are being
  92.     // displayed in.
  93.     fDisplayFrames = new CLinkedList;
  94. }
  95.  
  96.  
  97. void CMyPart::InitPartFromStorage(
  98.                 Environment*                ev,
  99.                 ODStorageUnit*                storageUnit,
  100.                 ODPart*                        partWrapper
  101. )
  102. {
  103.     // Create a list to keep track of the frames we are being
  104.     // displayed in.
  105.     fDisplayFrames = new CLinkedList;
  106.  
  107.  // read in our list of display frames
  108.     storageUnit->Focus(ev, kODPropDisplayFrames, kODPosUndefined,
  109.                                     kODWeakStorageUnitRefs, 0, kODPosUndefined);
  110.     ODULong    size = storageUnit->GetSize(ev);
  111.     storageUnit->SetOffset(ev, 0);    
  112.     
  113.     for ( ODULong offset = 0; offset < size; offset += sizeof(ODStorageUnitRef) )
  114.     {        
  115.         StorageUnitGetValue(storageUnit, ev, sizeof(ODStorageUnitRef), weakRef);
  116.             
  117.         if ( storageUnit->IsValidStorageUnitRef(ev, weakRef) )
  118.         {        
  119.             ODFrame *frame = storageUnit->GetDraft(ev)->
  120.                             GetFrame(ev, storageUnit->GetIDFromStorageUnitRef(ev, weakRef));
  121.             fDisplayFrames->Add((ODPtr)frame);
  122.         }
  123.     }
  124. }
  125.  
  126.  
  127. void CMyPart::DisplayFrameAdded(
  128.                 Environment*                ev,
  129.                 ODFrame*                    frame
  130. )
  131. {
  132.     frame->IncrementRefCount(ev);
  133.     fDisplayFrames->Add((ODPtr)frame);
  134. }
  135.  
  136.  
  137. void CMyPart::DisplayFrameConnected(
  138.                 Environment*                ev,
  139.                 ODFrame*                    frame
  140. )
  141. {
  142.     if (!fDisplayFrames->Contains((ODPtr)frame) )
  143.     {
  144.         frame->IncrementRefCount(ev);
  145.         fDisplayFrames->Add((ODPtr)frame);
  146.     }
  147. }
  148.  
  149.  
  150. void CMyPart::DisplayFrameRemoved(
  151.                 Environment*                ev,
  152.                 ODFrame*                    frame
  153. )
  154. {
  155.     fDisplayFrames->Remove((ODPtr)frame);
  156.     frame->Release(ev);
  157. }
  158.  
  159.  
  160. void CMyPart::DisplayFrameClosed(
  161.                 Environment*                ev,
  162.                 ODFrame*                    frame
  163. )
  164. {
  165.     fDisplayFrames->Remove((ODPtr)frame);
  166.     frame->Release(ev);
  167. }
  168.  
  169.  
  170.  
  171. void CMyPart::Externalize(
  172.                 Environment*                ev,
  173. )
  174. {
  175.     ODStorageUnitRef    weakRef;
  176.  ODStorageUnit* su = this->GetStorageUnit(ev);
  177.     ODSUForceFocus(su, kODPropDisplayFrames, kODWeakStorageUnitRefs);
  178.     
  179.     // Persistent object references are stored in a side table, rather than
  180.     // in the property/value stream. Thus, deleting the contents of a value
  181.     // will not "delete" the references previously written to that value. To
  182.     // completely "delete" all references written to the value, we must
  183.     // remove the value and add it back.
  184.  
  185.     su->Remove(ev);
  186.     su->AddValue(ev, kODWeakStorageUnitRefs);
  187.  
  188.     for ( CLink* link = fDisplayFrames->First();
  189.          link->Content();
  190.          link = link->Next() )
  191.     {
  192.         frame = (ODFrame*) link->Content();
  193.         frameID = frame->GetID(ev);
  194.         
  195.         // Write out weak references to each of the part's display frames.
  196.         su->GetWeakStorageUnitRef(ev, frameID, weakRef);
  197.         StorageUnitSetValue(su, ev, sizeof(ODStorageUnitRef), weakRef);
  198.     }
  199. }
  200.  
  201.  
  202. void CMyPart::ReleaseAll(
  203.                 Environment*                ev,
  204. )
  205. {
  206.  ASSERT(fDisplayFrames->First() == kODNULL);
  207. }
  208.  
  209.  
  210.  
  211.  
  212.